Node / meshtastic / Meshtastic-Android / files / docs / decisions / navigation3-api-alignment-2026-03.md

Displaying Raw • View rendered • Download

<!--

Tff7b72- Copyright (c) 2026 Meshtastic LLC

Tff7b72-

- This program is free software: you can redistribute it and/or modify

Tff7b72- it under the terms of the GNU General Public License as published by

Tff7b72- the Free Software Foundation, either version 3 of the License, or

Tff7b72- (at your option) any later version.

-->

Tc9d1d9# Navigation 3 & Material 3 Adaptive — API Alignment Audit

**Date:** 2026-03-26

**Status:** Active

**Scope:** Adoption of Navigation 3 Ta5d6ff`1.1.0-beta01` Scene APIs, transition metadata, ViewModel scoping, and Material 3 Adaptive integration.

**Supersedes:** [Ta5d6ff`navigation3-parity-2026-03.md`](navigation3-parity-2026-03.md) Alpha04 Changelog section (versions updated).

Tc9d1d9## Current Dependency Baseline

| Library | Version | Group |

|---|---|---|

| Navigation 3 UI | Ta5d6ff`1.1.0-beta01` | Ta5d6ff`org.jetbrains.androidx.navigation3:navigation3-ui` |

| Navigation Event | Ta5d6ff`1.1.0-alpha01` | Ta5d6ff`org.jetbrains.androidx.navigationevent:navigationevent-compose` |

| Lifecycle ViewModel Navigation3 | Ta5d6ff`2.11.0-alpha02` | Ta5d6ff`org.jetbrains.androidx.lifecycle:lifecycle-viewmodel-navigation3` |

| Material 3 Adaptive | Ta5d6ff`1.3.0-alpha06` | Ta5d6ff`org.jetbrains.compose.material3.adaptive:adaptive*` |

| Material 3 Adaptive Navigation Suite | Ta5d6ff`1.11.0-alpha05` | Ta5d6ff`org.jetbrains.compose.material3:material3-adaptive-navigation-suite` |

| Compose Multiplatform | Ta5d6ff`1.11.0-beta01` | Ta5d6ff`org.jetbrains.compose` |

| Compose Multiplatform Material 3 | Ta5d6ff`1.11.0-alpha05` | Ta5d6ff`org.jetbrains.compose.material3:material3` |

Tc9d1d9## API Audit: What's Available vs. What We Use

Tc9d1d9### 1. NavDisplay — Scene Architecture (available since `1.1.0-alpha04`, stable in `beta01`)

**Available APIs we're NOT using:**

| API | Purpose | Status in project |

|---|---|---|

| Ta5d6ff`sceneStrategies: List<SceneStrategy<T>>` | Allows NavDisplay to render multi-pane Scenes | ✅ Used — Ta5d6ff`DialogSceneStrategy`, Ta5d6ff`ListDetailSceneStrategy`, Ta5d6ff`SupportingPaneSceneStrategy`, Ta5d6ff`SinglePaneSceneStrategy` |

| Ta5d6ff`SceneStrategy<T>` interface | Custom scene calculation from backstack entries | ✅ Used via built-in strategies |

| Ta5d6ff`DialogSceneStrategy` | Renders Ta5d6ff`entry<T>(metadata = dialog())` entries as overlay Dialogs | ✅ Adopted |

| Ta5d6ff`SceneDecoratorStrategy<T>` | Wraps/decorates scenes with additional UI | ❌ Not used |

| Ta5d6ff`NavEntry.metadata` | Attaches typed metadata to entries (transitions, dialog hints, Scene classification) | ✅ Used — Ta5d6ff`ListDetailSceneStrategy.listPane()`, Ta5d6ff`.detailPane()`, Ta5d6ff`.extraPane()` |

| Ta5d6ff`NavDisplay.TransitionKey` / Ta5d6ff`PopTransitionKey` / Ta5d6ff`PredictivePopTransitionKey` | Per-entry custom transitions via metadata | ❌ Not used |

| Ta5d6ff`transitionSpec` / Ta5d6ff`popTransitionSpec` / Ta5d6ff`predictivePopTransitionSpec` params | Default transition animations for NavDisplay | ✅ Used — 350 ms crossfade |

| Ta5d6ff`sharedTransitionScope: SharedTransitionScope?` | Shared element transitions between scenes | ❌ Not used |

| Ta5d6ff`entryDecorators: List<NavEntryDecorator<T>>` | Wraps entry content with additional behavior | ✅ Used — Ta5d6ff`SaveableStateHolderNavEntryDecorator` + Ta5d6ff`ViewModelStoreNavEntryDecorator` |

**APIs we ARE using correctly:**

| API | Usage |

|---|---|

| Ta5d6ff`NavDisplay(backStack, entryProvider, modifier)` | Both Ta5d6ff`app/Main.kt` and Ta5d6ff`desktop/DesktopMainScreen.kt` |

| Ta5d6ff`rememberNavBackStack(SavedStateConfiguration, startKey)` | Backstack persistence |

| Ta5d6ff`entryProvider<NavKey> { entry<T> { ... } }` | All feature graph registrations |

| Ta5d6ff`NavigationBackHandler` from Ta5d6ff`navigationevent-compose` | Used with Ta5d6ff`ListDetailSceneStrategy` |

Tc9d1d9### 2. ViewModel Scoping (`lifecycle-viewmodel-navigation3` `2.11.0-alpha02`)

**Key finding:** The Ta5d6ff`ViewModelStoreNavEntryDecorator` is available and provides automatic per-entry ViewModel scoping tied to backstack lifetime. The project passes it as an Ta5d6ff`entryDecorator` to Ta5d6ff`NavDisplay` via Ta5d6ff`MeshtasticNavDisplay` in Ta5d6ff`core:ui/commonMain`.

ViewModels obtained via Ta5d6ff`koinViewModel()` inside Ta5d6ff`entry<T>` blocks are scoped to the entry's backstack lifetime and automatically cleared when the entry is popped.

Tc9d1d9### 3. Material 3 Adaptive — Nav3 Scene Integration

**Key finding:** The JetBrains Ta5d6ff`adaptive-navigation3` artifact at Ta5d6ff`1.3.0-alpha06` includes Ta5d6ff`ListDetailSceneStrategy` and Ta5d6ff`SupportingPaneSceneStrategy`. The project uses both via Ta5d6ff`rememberListDetailSceneStrategy` and Ta5d6ff`rememberSupportingPaneSceneStrategy` in Ta5d6ff`MeshtasticNavDisplay`, with draggable pane dividers via Ta5d6ff`VerticalDragHandle` + Ta5d6ff`paneExpansionDraggable`.

This means the project **successfully** uses the M3 Adaptive Scene bridge through Ta5d6ff`NavDisplay(sceneStrategies = ...)`. Feature entries annotate themselves with Ta5d6ff`ListDetailSceneStrategy.listPane()`, Ta5d6ff`.detailPane()`, or Ta5d6ff`.extraPane()` metadata.

**When to revisit:** Monitor the JetBrains adaptive fork for Ta5d6ff`MaterialListDetailSceneStrategy` inclusion. It will likely arrive when the JetBrains fork catches up to the AndroidX Ta5d6ff`1.3.0-alpha09+` feature set.

Tc9d1d9### 4. NavigationSuiteScaffold (`1.11.0-alpha05`)

**Status:** ✅ Adopted (2026-03-26). Ta5d6ff`MeshtasticNavigationSuite` now uses Ta5d6ff`NavigationSuiteScaffold` with Ta5d6ff`calculateFromAdaptiveInfo()` and custom Ta5d6ff`NavigationSuiteType` coercion. No further alignment needed.

Tc9d1d9## Prioritized Opportunities

Tc9d1d9### P0: Add `ViewModelStoreNavEntryDecorator` to NavDisplay (high-value, low-risk)

**Status:** ✅ Adopted (2026-03-26). Each backstack entry now gets its own Ta5d6ff`ViewModelStoreOwner` via Ta5d6ff`rememberViewModelStoreNavEntryDecorator()`. ViewModels obtained via Ta5d6ff`koinViewModel()` are automatically cleared when their entry is popped. Encapsulated in Ta5d6ff`MeshtasticNavDisplay` in Ta5d6ff`core:ui/commonMain`.

**Impact:** Fixes subtle ViewModel leaks where popped entries retain their ViewModel in the Activity/Window store. Eliminates the need for manual Ta5d6ff`key = "metrics-$destNum"` ViewModel keying patterns over time.

Tc9d1d9### P1: Add default NavDisplay transitions (medium-value, low-risk)

**Status:** ✅ Adopted (2026-03-26). A shared 350 ms crossfade (Ta5d6ff`fadeIn` + Ta5d6ff`fadeOut`) is applied for both forward and pop navigation via Ta5d6ff`MeshtasticNavDisplay`. This replaces the library's platform defaults (Android: 700 ms fade; Desktop: no animation) with a faster, consistent transition.

**Impact:** Immediate UX improvement on both Android and Desktop. Desktop now has visible navigation transitions.

Tc9d1d9### P2: Adopt `DialogSceneStrategy` for navigation-driven dialogs (medium-value, medium-risk)

**Status:** ✅ Adopted (2026-03-26). Ta5d6ff`MeshtasticNavDisplay` includes Ta5d6ff`DialogSceneStrategy` in Ta5d6ff`sceneStrategies` before Ta5d6ff`SinglePaneSceneStrategy`. Feature modules can now use Ta5d6ff`entry<T>(metadata = DialogSceneStrategy.dialog()) { ... }` to render entries as overlay Dialogs with proper backstack lifecycle and predictive-back support.

**Impact:** Cleaner dialog lifecycle management available for future dialog routes. Existing dialogs via Ta5d6ff`AlertHost` are unaffected.

Tc9d1d9### Consolidation: `MeshtasticNavDisplay` shared wrapper

**Status:** ✅ Adopted (2026-03-26). A new Ta5d6ff`MeshtasticNavDisplay` composable in Ta5d6ff`core:ui/commonMain` encapsulates the standard Ta5d6ff`NavDisplay` configuration:

Tff7b72- Entry decorators: Ta5d6ff`rememberSaveableStateHolderNavEntryDecorator` + Ta5d6ff`rememberViewModelStoreNavEntryDecorator`

Tff7b72- Scene strategies: Ta5d6ff`DialogSceneStrategy` + Ta5d6ff`SinglePaneSceneStrategy`

Tff7b72- Transition specs: 350 ms crossfade (forward + pop)

Both Ta5d6ff`app/Main.kt` and Ta5d6ff`desktop/DesktopMainScreen.kt` now call Ta5d6ff`MeshtasticNavDisplay` instead of configuring Ta5d6ff`NavDisplay` directly. The Ta5d6ff`lifecycle-viewmodel-navigation3` dependency was moved from host modules to Ta5d6ff`core:ui`.

Tc9d1d9### P3: Per-entry transition metadata (low-value until Scene adoption)

Individual entries can declare custom transitions via Ta5d6ff`entry<T>(metadata = NavDisplay.transitionSpec { ... })`. This is most useful when different route types should animate differently (e.g., detail screens slide in, settings screens fade).

**Impact:** Polish improvement. Low priority until default transitions (P1) are established. Now unblocked by P1 adoption.

Tc9d1d9### Deferred: Custom Scene strategies

The Ta5d6ff`ListDetailSceneStrategy` and Ta5d6ff`SupportingPaneSceneStrategy` are adopted and working. Consider writing additional custom Ta5d6ff`SceneStrategy` implementations for specialized layouts (e.g., three-pane "Power User" scenes) as the Navigation 3 Scene API matures.

Tc9d1d9## Decision

Tf85149~~Adopt **P0** (ViewModel scoping) and **P1** (default transitions) now. Defer P2/P3 and Scene-based multi-pane until the JetBrains adaptive fork adds `MaterialListDetailSceneStrategy`.~~

**Updated 2026-03-26:** P0, P1, and P2 adopted and consolidated into Ta5d6ff`MeshtasticNavDisplay` in Ta5d6ff`core:ui/commonMain`. P3 (per-entry transitions) is available for incremental adoption by feature modules. Scene-based multi-pane remains deferred.

Tc9d1d9## References

Tff7b72- Navigation 3 source: Ta5d6ff`navigation3-ui` Ta5d6ff`1.1.0-beta01` (inspected from Gradle cache)

Tff7b72- [Ta5d6ff`NavDisplay.kt`](https://cs.android.com/androidx/platform/frameworks/support/+/main:navigation3/navigation3-ui/src/commonMain/kotlin/androidx/navigation3/ui/NavDisplay.kt) (upstream)

Tff7b72- [Ta5d6ff`SceneStrategy.kt`](https://cs.android.com/androidx/platform/frameworks/support/+/main:navigation3/navigation3-ui/src/commonMain/kotlin/androidx/navigation3/scene/SceneStrategy.kt) (upstream)

Tff7b72- Material 3 Adaptive JetBrains fork: Ta5d6ff`org.jetbrains.compose.material3.adaptive` Ta5d6ff`1.3.0-alpha06`